Improve cache_size and cache_size_percent descriptions #696
Conversation
✅ Deploy Preview for redpanda-docs-preview ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify site configuration. |
|
Hi @daisukebe . Is there an equivalent PR to the source code? Asking because the properties are extracted from automation through the source code. If they're not, it's ok, as I can include as part of my PR to source. |
|
@Deflaimun , ah not really. Once we update the description in the code https://github.com/redpanda-data/redpanda/blob/dev/src/v/config/configuration.cc#L2407-L2427, will the doc be updated automatically? |
|
Not 100% automated, as in a CI/CD process. But currently a manual process where we run https://github.com/Deflaimun/redpanda-property-extractor/blob/main/property_extractor.py Based on the release tag. However we did a number of improvements on the descriptions and I have to forward a PR to source updating them. |
|
Awesome, thank you @Deflaimun ! |
There was a problem hiding this comment.
@daisukebe let me know how this suggestion sounds. cc @Deflaimun
modules/reference/pages/properties/object-storage-properties.adoc
Outdated
Show resolved
Hide resolved
modules/reference/pages/properties/object-storage-properties.adoc
Outdated
Show resolved
Hide resolved
Co-authored-by: Kat Batuigas <[email protected]>
Co-authored-by: Kat Batuigas <[email protected]>
|
LGTM and committed. Thank you for making it clearer @kbatuigas ! |
| @@ -85,7 +85,7 @@ AWS or GCS bucket that should be used to store data. | |||
|
|
|||
| Max size of object storage cache. | |||
|
|
|||
| If both this property and <<cloud_storage_cache_size_percent>> are set, Redpanda uses the minimum of the two. | |||
| If both this property and <<cloud_storage_cache_size_percent>> are set, Redpanda uses the minimum of the two. If one of them is set to 0, Redpanda uses the non-zero one. If they are both set to 0, the cache size is 0. | |||
There was a problem hiding this comment.
Before making this change, I'd want to see what happens if the cache size is actually 0. This makes it sound like we support a cache size of 0, but I imagine cloud storage just wont work below some minimal cache size.
There was a problem hiding this comment.
any resolution on this @jcipar @daisukebe ?
There was a problem hiding this comment.
Given there's no guardrails on setting to zero from preventing, we should document like below?
If both this property and <<cloud_storage_cache_size_percent>> are set, Redpanda uses the minimum of the two. If one of them is set to 0, Redpanda uses the non-zero one. Redpanda strongly recommends you do not set both of them to zero.
There was a problem hiding this comment.
@jcipar and @WillemKauf Looks like this PR is stuck and awaiting your guidance here. Please respond asap. Thx.
There was a problem hiding this comment.
Hi @Feediver1, I just put out a PR that will update the behaviour here and (hopefully) make the update to the docs more straight-forward. We will now prevent the following invalid configurations:
cloud_storage_cache_sizeandcloud_storage_cache_size_percentcannot both be 0cloud_storage_cache_sizecannot be0whilecloud_storage_cache_size_percentisnil(std::nullopt)
I would say something like:
If both this property and <<cloud_storage_cache_size_percent>> are set, Redpanda uses the minimum of the two. If one of them is set to 0, Redpanda uses the non-zero one. These properties cannot both be `0` simultaneously.
Hope this helps.
There was a problem hiding this comment.
@WillemKauf @jcipar - The description has now been updated to reflect the change in the code. Please could you take a look and approve.
Also, please provide guidance on what happens when both properties are set to 0 so that we can provide troubleshooting advice where necessary.
There was a problem hiding this comment.
If the user attempts to set both configs to 0 via rpk cluster config edit, the configuration will be rejected (not applied) and the error message Cannot set both cloud_storage_cache_size and cloud_storage_cache_size_pct to 0. will be provided.
modules/reference/pages/properties/object-storage-properties.adoc
Outdated
Show resolved
Hide resolved
| @@ -601,7 +601,7 @@ Divide the object storage cache across the specified number of buckets. This onl | |||
|
|
|||
| Maximum size of the cloud cache as a percentage of unreserved disk space (see config_ref:disk_reservation_percent,true,cluster-properties[]). The default value for this option is tuned for a shared disk configuration. Consider increasing the value if using a dedicated cache disk. | |||
|
|
|||
| The property <<cloud_storage_cache_size,`cloud_storage_cache_size`>> controls the same limit expressed as a fixed number of bytes. If both `cloud_storage_cache_size` and `cloud_storage_cache_size_percent` are set, Redpanda uses the minimum of the two. | |||
| The property <<cloud_storage_cache_size>> controls the same limit expressed as a fixed number of bytes. If both `cloud_storage_cache_size` and `cloud_storage_cache_size_percent` are set, Redpanda uses the minimum of the two. If one of these properties is set to 0, Redpanda applies the non-zero value. If they are both set to 0, the cache size is 0. | |||
There was a problem hiding this comment.
This seems to contradict the text above, and how I understand the code. I think this should also read "These properties cannot both be 0."
Co-authored-by: Jake Cahill <[email protected]>
|
Apologies for not updating from me. I will gather them up this week. Thank you. |
Description
Added additional explanations to the
cloud_storage_cache_sizeandcloud_storage_cache_size_percentdescriptions in https://docs.redpanda.com/current/reference/properties/object-storage-propertiesReview deadline: N/A
Adding @jcipar as a SME reviewer
Page previews
Checks